Tech Arsenal 1/Tech Arsenal (Arsenal Computer).ISO/tek-01/codesmit.zip/CS.DOC

Text File | 1992-01-07 | 19KB | 496 lines

                      Welcome to CodeSmith

CodeSmith is an application generator. It's goal is to provide
you the programmer with near instant complete single database,
multiple screen, network/signle user applications without writing
a line of code. This is done by designing a data screen with
CodeSmith's internal screen painter. Your design can be based on
all or part of an existing database, one or more previous designs
or you can begin from scratch. In any case CodeSmith will write
the programs to manage your new/old database.

                     THE SAMPLE APPLICATION

Your created application (we'll use the name SAMPLE) will be
optimized for rapid data entry, retrieval, and editing. Searches
may be based on up to 15 indexes plus a user defined temp index
if less than 15 are used. Standard navigation features like
next/previous record, Go To record #, top, bottom, first record,
last record and skip are automatically provided. Multiple screens
are simply accessed by PgDn/PgUp.

A view command allows you to switch from full screen mode to
browse mode where each record is on a single line. Function key
assignments for use when adding records are accessed from the
opening menu. The user may assign text strings to function keys
F3 thru F10. F2 will replicate the data contained in the last
record, like SET CARRY ON. Any field may be assigned to
automatically replicate itself. F-Key and Dupe Key settings are
saved in .MEM files and restored at program start up.

CodeSmith generates the full and complete source code for your
application design with no hidden libraries. The only
requirements are those needed by Clipper itself.

In addition to generating a complete application, you can also
generate code fragments; input/output screens and procedures to
create a database structure. A real useful tool when changing an
existing application or when you just need a screen.

An Ad Hoc report writer allows the user to make their own
columnar reports.

A Label Maker is included to create mailing labels from your
database or free form. Labels are 3 for a Laser Printer and 1 up
for dot matrix. If using a laser printer please select the proper
printer. The label maker prints 30 characters to a line and uses
a 12cpi font. HP Series II and IID do not come with a built in
12cpi font so 10cpi is compressed to 12cpi.

Both the label maker and report writer respect index order and
filter settings.

Printer selection is available for 16 popular models including HP
Lasers. These values are stored in public memvars (see
sample.prg) and can be used for pitch changes in reports that you
may add later. These values are saved to CSPRINT.MEM and are
restored at program start up.

Laser Utilities provides access to most of the HP Laser front
panel options from a menu. If you're lazy like me it's great to
do a form feed or change trays without leaving your chair. You
may also switch from portrait to landscape or make pitch and line
spacing changes prior to writing a report.


Terminology:

Object: An item on the screen. Can be a field, text, box or line.

<X> Single letter command. Example: Type X to exit.


File Naming Convention:

Prior to generating code you will be prompted to give your
application a name. The .dbf file it is to manage shares the same
name. Files unique to your application will be based on the first
5 or 6 characters of the named application. In the following
example we will use the name SAMPLE.

SAMPLE.CS1  - Your Screen Design
SAMPLE.CS2  - Index keys for this design


CodeSmith produces the following files:

SAMPLE.PRG      Main Menu
SAMPLADD.PRG    Add Records
SAMPLGET.PRG    Search/Edit Record
SAMPLHLP.PRG    Help File
SAMPLE.MAK      Rmake Make file
SAMPLE.LNK      Blinker Link File
SAMPLE.RTL      RTlink Link File
GO.BAT          Generic, used to compile and link application.
CS.CH           Generic Header File. Contains system colors.
CSGENRL.PRG     Generic Functions and Procedures
CSLABEL.PRG     Generic Label Maker
CSVIEW.PRG      Generic Browser
CSREPORT.PRG    Generic Report Writer
CSQBE.PRG       Generic Query by Example/Complex Filter Builder
CSLOCKS.PRG     Networking Functions

These 'generic' files are produced the same way each time so
there is no problem in overwriting them in different sessions
provided you have not modified them. The networking functions in
cslock.prg are either real or dummys. If use choose networking
code you get the real functions, otherwise the functions just
return a logical .t.. In this way the source code for both
network and single user applications is the same and there is no
performance penalty when selecting single user code. This also
greatly simplifies changing from one to the other.


SAMPLE.EXE will produce.

SAMPLE.DBF    (ONLY IF NEEDED)
SAMPLE1.NTX to SAMPLE15.NTX (ONLY IF NEEDED)
SAMPLKEY.MEM   F3-F10 key assignments
SAMPLDUP.MEM   Fields to Dupe in Add Mode (like SET CARRY ON)
CSPRINT.MEM    Printer pitch control macros


                         GETTING STARTED
                     WITH THE SCREEN PAINTER


CURSOR/OBJECT MOVEMENT:

Cursor movement is done with the familiar arrow keys.

To move an object, place the cursor on the object (or box
outline) and press <Enter>. Use the arrow keys to move the object
around and press <Enter> to anchor it in place.

To move the entire screen, place the cursor anywhere NOT on an
object and outside of any box, then press <Enter>. Move and
anchor the screen as above.

To move the contents of a box, place the cursor inside a box
outline and press <Enter>, use the arrow keys to move the
contents around and press <Enter> to anchor in place.

<Ctrl> <Right Arrow> moves cursor to the next object,
<Ctrl> <Left Arrow> moves cursor to the previous object.

SCREEN CONTROL:
Ctrl PgDn/Ctrl PgUp will get you from one CodeSmith
screen/window/page to the next. By using multiple sceens, your
application can easily accomodate more fields than can be fit on
one screen. Also you may combine or merge several applications
provided a one to one relationship exists.

EDITING COMMANDS: May be issued from the keyboard or from the
main menu.

<A>  ADD OBJECT:
Select box, character, date, line, logical, memo, numeric, text
or User Defined.

Box: Select box type.
     Drag box from the cursor position, down and to the right.
     Press <Enter> to anchor it in place. You may edit or
     reposition the box later.
Box Attributes: Select an optional color (more about colors
later).

Character, Date, Logical, Memo & Numeric:
Field Attributes:

Name: Each database field needs a unique name.

Order: This is the sequence that the field will appear when
adding and editing.

Description: Field descriptions are used for column titles in
view/browse mode. The default is the field name. Take an extra
minute to give your fields a description in English, your
customers will appreciate it.

Length: Character and numeric field lengths must be entered.
Date, Logical and Memo are automatically entered.

Picture: Optional- PICTURE clause entered without quotes.

Color GET: Optional-This is the color used for the field when
in add or edit mode. Use this option when you want a COLOR
different from the system SETCOLOR() setting. CodeSmith sets the
system color to a manifest constant called colornorm (lower case
without quotes) contained in cs.ch and defined as
'w+/b,gr+/rb,,,bg+/b'.

COLOR may be input using the pre-defined manifest constants
colornorm/colorrev or as literal string such as 'bg+/b' (with
quotes) or you may select colors from CodeSmith's visual color
picker by pressing F3.

If the COLOR thing is confusing, remember that it is an option
and may be ignored.


Color SAY: Optional-This is the color used for the field when
in show mode.

WHEN Clause: Optional- WHEN is new to 5.01 and is a pre-condition
expression which must be met before the cursor will be allowed to
enter the GET during a READ. For example, suppose we have a
character field CPHONE to be used to hold a company phone number.
We could skip this field if the COMPANY field was empty using the
syntax !EMPTY(m->company). The produced code would look like:

@ xx,yy get CPHONE WHEN !EMPTY(m->COMPANY)

m-> is used to distinguish the memory variable and the field
which share the same name. Memory variables are used rather than
modifying the fields directly which allows for abandoning changes
prior to a save.

VALID Clause: Optional- VALID is a post-condition expression
which must be met before the cursor will be allowed to leave the
GET during a read.
Example: @ xx,yy get m->amount VALID m->amount > 0.
In this example only numbers greater than 0 will be accepted.

Example: @ xx,yy get m->state VALID state(@state)
Here the condition which must be met is a function state().
STATE() is generated whether it is used or not and can be found
in csgenrl.prg. It is a pop-up validation function containing
state and territory two letter abbreviations which is activated
when an incorrect state is entered. Notice the parameter is
passed to the function by reference, @state and therefore the m->
is omitted.

After defining the FIELD it is redisplayed showing it's name plus
ascii character 176 to pad it to length. If the name exceeds the
length of the field it is truncated. For example a logical field
with the name badaddr with be displayed as 'b'.

Line: Select line type from an ASCII chart.
     Use the right arrow key to draw line.
     Press <Enter> to save it.
Line Attributes: Select an optional color.


Text: Type in desired text.
      Press <Enter> to save.
Text Attributes: Select an optional color.


USER DEFINED allows you to insert custom code directly into your
application. This may be a line of code up to 250 characters in
length. Typical uses are procedure or function calls or maybe a
calculated result to display on screen. You can display a memo on
screen e.g. MEMOEDIT(fieldname, t, l, b, r, .f., .f.) or anything
that can be expressed in 250 character. The uses are limited by
your imagination and needs.

USER DEFINED Attributes: Currently we have three places where
your USER DEFINED CODE may be inserted.

1) Add- When adding a record.

2) GET- When editing a record.

3) Show- When displaying/showing a record.

Future editions will have many more insertion points such as
after a read in add or edit mode so that you may have multiple
screens and also in several locations in SAMPLE.PRG, the main
menu. Let me know what you want and I'll try to accommodate.

Order: This is the sequence that your code will be processed in
relation to your other fields.

User Defined Fields are notated by the Greek letter µ (Mu) to
make them distinctive.


<C>  COPY OBJECT:
Place the cursor on text, line, USER DEFINED FIELD or box outline
to be copied and press <C>. The copied (duplicated object) will
flash. Use arrows keys to move it into position the press <Enter>
to anchor it in place. Boxes are copied less contents. Duplicate
data fields are not allowed.


<D>  DELETE OBJECT:
Place the cursor on an object (for boxes use the outline), or
empty row to delete and press <D>. There is no undo so it is
suggested that you save your work <S> from time to time.


<E>  EDIT OBJECT
Place the cursor on the object or box outline you wish to edit
and press <E>. Boxes may be resized, text and lines and USER
DEFINED code may be modified and database field attributes except
data type may be altered.


<F>  Field Selection:
Select additional fields not already on the screen. If the
current session began with a previous design (.CS1 file) or a
blank screen, a DBF file (<G> option) needs to be selected prior
to selecting fields. CodeSmith will check all windows for
duplicate fields.


<G> Get DBF file:
Choose a .DBF file from which fields may be selected.


<I>  INSERT ROW:
Well not exactly. Unlike a wordprocessor we cannot actually
insert a row but we can move all objects from the line containing
the cursor down one row provided the last line is empty.


<L>  setMode():
Change screen display to 25/43/50 lines; monitor and graphics
card permitting.


<N>  New Screen File:
Import a file, .DBF or a previous session saved as a .CS1 file.
If the current window contains data, the imported file will be
added to a new window. You may freely switch windows with the
Ctrl PgDn/Ctrl PgUp keys. Your application will access these
multiple screens, in order, using the PgDn/PgUp keys.  Note that
when importing a file, CodeSmith will not check for duplicate
fields! It is up to you to rename any duplicate fields prior to
application generation. This approach was taken in favor of
omitting or renaming the duplicate fields at import time.


<P>  Preview mode simulates the appearance of your application in
both show and add/edit modes. Your picture clauses and colors are
used but valids and whens are not. This will give you a good idea
what your finished screens will look like.

<R>  Redraw Screen:
Use after overlapping an object if you see phantom characters.


<S>  Save Work:
Save your application design for future use. This is a database
file with a .CS1 (added for you) extension. Index keys and de
scriptions are save to a file using the same name but a .CS2
extension.


<T>  Toggle Menu:
Turn the main footer menu on/off.


<X>  eXit to DOS


<Z>  Zap Screen:
Clears Screen. Save your work first since there is no undo
feature!

Global Field Attributes:

COLORs, field order/numbers, PICTUREs VALIDs and WHENs may be
entered or modified for all fields at once. This is much faster
that editing each field and then remembering the individual
settings. I will usually input the bare necessities first and
then do my colors, field numbers, valids and whens here before
generating my application.


INDEX KEYS:
CodeSmith allows up to 15 index keys and descriptions. Index keys
may be up to 250 characters and there is no syntax checking. This
will allow for indexing on a UDF. Descriptions may be up to 65
characters. This information is stored in a data base with an
extension .CS2. This file tags along with it's related (.CS1)
screen file and is not individually accessible via CodeSmith
except through the option menu.

If you select less that 15 indexes your application will provide
the option of creating a temp index. Index file names are the
first 6 characters of the database plus 1,2,. . .15. The number
of indexes chosen is stored in a public memvar. Your application
can then figure out if a temp index is available and if so make
use of it. The description for the temp index is it's key.
Selecting Re-Index from the application's main menu will index on
the header/key of the temp index, effectively the same as the
re-index command. All other indexes will be re-created since
their keys have been built into the application. The temp index
is real handy when you deliver an application and your customer
wants search by a new key.

Generate Full Application: Create a complete application.

Generate Code Fragment:
Produce @ SAYs and @ GETS based on your screen design, index keys
and descriptions plus procedures to create your database design
both in Summer '87 and 5.01. This comes in handy when you need to
make changes to an existing application, especially those that
are not created by CodeSmith.


                         QUICK TUTORIAL

From the DOS prompt type CS <Enter>.

Using the arrows keys, highlight SAMPLE.CS1 and press <Enter>.

At the next screen press <M> Main Menu.

Using the arrow keys, highlight Generate Full Application and
press <Enter>

At the prompt for the application name type SAMPLE and press
<Enter>.

Last prompt, select Network or Single User code.

CodeSmith will now generate about 5,000 lines of 5.01 program
code.

When finished you see a prompt about compiling and linking the
application.

Press <ESC> twice,  then press <X> to Exit to DOS.

At the DOS prompt type GO SAMPLE.

GO.BAT will tell Rmake to process SAMPLE.MAK which will compile
all programs. Next it will tell SAMPLE.RMK to link the
application using RTlink. If you are using Blinker, you can REM
out the line calling RtLink.

Type SAMPLE <Enter>

Examine the application.

                          OWN YOUR OWN

CodeSmith and it's applications support 25, 43 and 50 line
displays. The default for both is the current display mode. If
for example you are currently in 25 line mode and you want to
generate an application for 50 line VGA displays, use the <L>
setmode()/ Lines option. This will give you twice the screen area
to work with. The finished application defaults to the current
mode so begin application by typing SAMPLE 50.

After doing the tutorial re-enter CodeSmith and experiment with
the supplied application design file provided, SAMPLE.CS1. Edit a
few fields to see their attributes. Add, modify and deleted
fields; move things around to get the feel of the screen painter.

I have not guided you through the creation of an application from
scratch because I have found that after a few minutes of learing
to navigate around the screen, users of CodeSmith need very
little prompting. Normally when I give a demo of CodeSmith, I let
the user sit in the drivers seat and only spend a couple of
minutes explaining the theory of operation. Many of us (myself
included) would rather use the application than read (boring)
documentation (like this) so I have attempted to keep the product
easy to use and kept the paper work to a minimum.

After playing with sample.cs1, start a new session by selecting
a .DBF file. Move things around to suit your taste and then
generate a full application.

At first glance it may appear that CodeSmith has a lot of options
to deal with, but not really. With the exception of entering
INDEX KEYS, (you can't search without an index) the others can be
ignored. With a little practice you can create a full working
application in a few minutes while your customer watches. Now
your customer can begin data entry, impressed at how efficient
you are, while you return to your office and . . .

CodeSmith is intended to relieve you of the mundane aspects of
programming. I use it for all my simple applications and as a
starting point for complex applications.

When was the last time bought a valuable programming tool for
only $49.00 (regular price is $129.00) ?

CodeSmith is being actively developed with changes on a daily
basis. Future versions will include relations and user defined
pop-up validation functions, etc. Let me know what you need.

The current (Christmas 1991) upgrade policy is 50% of the current
selling price. Beta testers get free upgrades.

If you have any problems, please give me a call, I want you to be
productive. I welcome your comments and suggestions.

Don Allred [phone]

Happy Programming!